/*
 * Copyright (c) 2007 jNetX.
 * http://www.jnetx.com
 * All rights reserved.
 *
 * This software is the confidential and proprietary information of
 * jNetX. You shall not disclose such Confidential Information and
 * shall use it only in accordance with the terms of the license
 * agreement you entered into with jNetX.
 *
 * $Id$
 */
package com.jnetx.javax.sip.header;

import javax.sip.header.ContentDispositionHeader;
import java.text.ParseException;

/**
 * The Content-Disposition header field describes how the message body or,
 * for multipart messages, a message body part is to be interpreted by the
 * UAC or UAS. This SIP header field extends the MIME Content-Type. Several
 * new "disposition-types" of the Content-Disposition header are defined by
 * SIP, namely:-
 * <ul>
 * <li>session - indicates that the body part describes a session, for either
 * calls or early (pre-call) media.
 * <li>render - indicates that the body part should be displayed or otherwise
 * rendered to the user.
 * <li>icon - indicates that the body part contains an image suitable as an
 * iconic representation of the caller or callee that could be rendered
 * informationally by a user agent when a message has been received, or
 * persistently while a dialog takes place.
 * <li>alert - indicates that the body part contains information, such as an
 * audio clip, that should be rendered by the user agent in an attempt to alert
 * the user to the receipt of a request, generally a request that initiates a
 * dialog.
 * </ul>
 * For backward-compatibility, if the Content-Disposition header field is
 * missing, the server SHOULD assume bodies of Content-Type application/sdp are
 * the disposition "session", while other content types are "render".
 * <p>
 * If this header field is missing, the MIME type determines the default
 * content disposition.  If there is none, "render" is assumed.
 * <p>
 * For Example:<br>
 * <code>Content-Disposition: session</code>
 *
 * @see javax.sip.header.ContentTypeHeader
 * @see javax.sip.header.ContentLengthHeader
 * @see javax.sip.header.ContentEncodingHeader
 * @see javax.sip.header.ContentLanguageHeader
 *
 * @author <a href="mailto:dparhonin@jnetx.ru">Dmitry Parhonin</a>
 * @version $Revision$
 */
public class ContentDispositionHeaderImpl extends ParametrizedHeaderBase implements ContentDispositionHeader {
    private String dispositionType;

    private static final ContentDispositionHeaderParser parser = new ContentDispositionHeaderParser();

    public ContentDispositionHeaderImpl() {
        super(ContentDispositionHeader.NAME);
    }

    ContentDispositionHeaderImpl(byte[] data, int start, int end) {
        super(ContentDispositionHeader.NAME, data, start, end);
    }

    public Object clone() {
        final ContentDispositionHeaderImpl header = new ContentDispositionHeaderImpl();
        header.cloneBase(this);
        if (parsed) {
            header.cloneParameters(this);
            header.dispositionType = this.dispositionType;
        }
        return header;
    }

    protected HeaderParser getParser() {
        return parser;
    }

    protected String getValueAsString() {
        return dispositionType;
    }

    /**
     * Sets the interpretation value of the message body or message body part
     * for this ContentDispositionHeader.
     *
     * @param dispositionType the new String value of the
     *                        disposition type.
     * @throws java.text.ParseException which signals that an error has been reached
     *                                  unexpectedly while parsing the dispositionType parameter.
     */
    public void setDispositionType(String dispositionType) throws ParseException {
        parse();
        this.dispositionType = dispositionType;
        invalidateHeaderData();
    }

    /**
     * Gets the interpretation of the message body or message body part of
     * this ContentDispositionHeader.
     *
     * @return interpretation of the message body or message body part
     */
    public String getDispositionType() {
        parse();
        return this.dispositionType;
    }

    /**
     * The handling parameter describes how the UAS should react if it
     * receives a message body whose content type or disposition type it
     * does not understand.  The parameter has defined values of "optional"
     * and "required".  If the handling parameter is missing, the value
     * "required" SHOULD be assumed.
     *
     * @param handling the new String value either "optional"
     *                 or "required".
     * @throws java.text.ParseException which signals that an error has been reached
     *                                  unexpectedly while parsing the handling parameter.
     */
    public void setHandling(String handling) throws ParseException {
        parse();
        setParameter("handling", handling);
        invalidateHeaderData();
    }

    /**
     * Gets the handling information of the unknown content disposition of the
     * ContentDispositionHeader.
     *
     * @return handling information for unknown content dispositions.
     */
    public String getHandling() {
        parse();
        return getParameter("handling");
    }
}
/*
 * $Log$
 */